package com.beauty.product.service;

import com.beauty.product.dto.PageResponse;
import com.beauty.product.dto.ProductAttributeDto;
import com.beauty.product.dto.ProductDto;
import com.beauty.product.dto.ProductImageDto;
import com.beauty.product.dto.ProductQueryParam;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

import java.util.List;

/**
 * 商品服务接口
 * <p>
 * 定义了商品管理相关的所有业务操作，包括商品的基本CRUD操作、
 * 商品图片管理、商品属性管理以及商品搜索等功能。
 * </p>
 * 
 * @author beauty-dev
 * @version 1.0
 */
public interface ProductService {
    
    /**
     * 创建新商品
     * 
     * @param productDto 商品数据传输对象，包含商品的详细信息
     * @return 返回创建成功的商品信息
     */
    ProductDto createProduct(ProductDto productDto);
    
    /**
     * 根据ID获取商品详情
     * 
     * @param id 商品ID
     * @return 返回指定ID的商品详细信息
     */
    ProductDto getProductById(String id);
    
    /**
     * 根据SKU获取商品详情
     * 
     * @param sku 商品SKU编码
     * @return 返回指定SKU的商品详细信息
     */
    ProductDto getProductBySku(String sku);
    
    /**
     * 根据查询参数搜索商品
     * 
     * @param param 查询参数对象，包含关键词、分类、价格范围等
     * @return 返回符合条件的商品分页结果
     */
    Page<ProductDto> getProducts(ProductQueryParam param);
    
    /**
     * 获取指定分类下的所有商品
     * 
     * @param categoryId 分类ID
     * @param pageNum 页码
     * @param pageSize 每页数量
     * @return 返回分类下的商品分页结果
     */
    Page<ProductDto> getProductsByCategory(Long categoryId, int pageNum, int pageSize);
    
    /**
     * 获取热门商品列表
     * <p>
     * 根据销量或其他热门指标筛选出热门商品
     * </p>
     * 
     * @param limit 返回商品数量
     * @return 返回热门商品列表
     */
    List<ProductDto> getHotProducts(int limit);
    
    /**
     * 获取新品列表
     * <p>
     * 根据创建时间筛选出最新上架的商品
     * </p>
     * 
     * @param limit 返回商品数量
     * @return 返回新品商品列表
     */
    List<ProductDto> getNewProducts(int limit);
    
    /**
     * 获取推荐商品列表
     * <p>
     * 获取被标记为推荐的商品列表
     * </p>
     * 
     * @param limit 返回商品数量
     * @return 返回推荐商品列表
     */
    List<ProductDto> getRecommendedProducts(int limit);
    
    /**
     * 更新商品信息
     * 
     * @param id 商品ID
     * @param productDto 更新的商品信息
     * @return 返回更新后的商品详情
     */
    ProductDto updateProduct(String id, ProductDto productDto);
    
    /**
     * 删除商品
     * 
     * @param id 要删除的商品ID
     */
    void deleteProduct(String id);
    
    /**
     * 商品上下架操作
     * 
     * @param id 商品ID
     * @param isPublished 是否上架，true表示上架，false表示下架
     */
    void publishProduct(String id, Boolean isPublished);
    
    /**
     * 为商品添加图片
     * 
     * @param productId 商品ID
     * @param imageDto 图片信息
     * @return 返回添加成功的图片信息
     */
    ProductImageDto addProductImage(String productId, ProductImageDto imageDto);
    
    /**
     * 获取商品的所有图片
     * 
     * @param productId 商品ID
     * @return 返回商品图片列表
     */
    List<ProductImageDto> getProductImages(String productId);
    
    /**
     * 删除商品图片
     * 
     * @param imageId 图片ID
     */
    void deleteProductImage(Long imageId);
    
    /**
     * 为商品添加属性
     * 
     * @param productId 商品ID
     * @param attributeDto 属性信息
     * @return 返回添加成功的属性信息
     */
    ProductAttributeDto addProductAttribute(String productId, ProductAttributeDto attributeDto);
    
    /**
     * 获取商品的所有属性
     * 
     * @param productId 商品ID
     * @return 返回商品属性列表
     */
    List<ProductAttributeDto> getProductAttributes(String productId);
    
    /**
     * 删除商品属性
     * 
     * @param attributeId 属性ID
     */
    void deleteProductAttribute(Long attributeId);
    
    /**
     * 根据关键词搜索商品
     * <p>
     * 对商品名称、描述、品牌等字段进行模糊查询
     * </p>
     * 
     * @param keyword 搜索关键词
     * @param pageable 分页参数
     * @return 返回搜索结果的分页数据
     */
    PageResponse<ProductDto> searchProducts(String keyword, Pageable pageable);
    
    /**
     * 高级搜索商品
     * <p>
     * 支持多条件组合查询，如商品名称、SKU、品牌、描述等
     * </p>
     * 
     * @param name 商品名称（可选）
     * @param sku 商品SKU（可选）
     * @param brand 商品品牌（可选）
     * @param description 商品描述（可选）
     * @param pageable 分页参数
     * @return 返回搜索结果的分页数据
     */
    PageResponse<ProductDto> advancedSearch(String name, String sku, String brand, String description, Pageable pageable);
    
    /**
     * 获取商品分页数据
     * <p>
     * 返回所有商品的分页列表，支持排序
     * </p>
     * 
     * @param pageable 分页参数
     * @return 返回商品分页数据
     */
    PageResponse<ProductDto> getProductsPage(Pageable pageable);
    
    /**
     * 获取指定图片的详细信息
     * 
     * @param imageId 图片ID
     * @return 返回图片详细信息
     */
    ProductImageDto getProductImage(Long imageId);
    
    /**
     * 更新商品图片信息
     * 
     * @param imageDto 更新的图片信息
     * @return 返回更新后的图片信息
     */
    ProductImageDto updateProductImage(ProductImageDto imageDto);
} 